SubAnt (Apache Ant API)

org.apache.tools.ant.taskdefs

## Class SubAnt

- java.lang.Object
- - org.apache.tools.ant.ProjectComponent
  - - org.apache.tools.ant.Task
    - - org.apache.tools.ant.taskdefs.SubAnt

- All Implemented Interfaces:
    java.lang.Cloneable

      public class SubAnt
      extends Task

  Calls a given target for all defined sub-builds. This is an extension of ant for bulk project execution.

  ## Use with directories

  subant can be used with directory sets to execute a build from different directories. 2 different options are offered

  - run the same build file /somepath/otherpath/mybuild.xml with different base directories use the genericantfile attribute
  - if you want to run directory1/build.xml, directory2/build.xml, .... use the antfile attribute. The base directory does not get set by the subant task in this case, because you can specify it in each build file.
  Since:
    Ant1.6

- - ### Field Summary

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SubAnt()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(ResourceCollection rc)` Adds a resource collection to the implicit build path.
    `void` | `addConfiguredTarget(Ant.TargetElement t)` Add a target to this Ant invocation.
    `void` | `addDirset(DirSet set)` Adds a directory set to the implicit build path.
    `void` | `addFilelist(FileList list)` Adds an ordered file list to the implicit build path.
    `void` | `addFileset(FileSet set)` Adds a file set to the implicit build path.
    `void` | `addProperty(Property p)` Corresponds to `<ant>`'s nested `<property>` element.
    `void` | `addPropertyset(PropertySet ps)` Corresponds to `<ant>`'s nested `<propertyset>` element.
    `void` | `addReference(Ant.Reference r)` Corresponds to `<ant>`'s nested `<reference>` element.
    `Path` | `createBuildpath()` Creates a nested build path, and add it to the implicit build path.
    `Path.PathElement` | `createBuildpathElement()` Creates a nested `<buildpathelement>`, and add it to the implicit build path.
    `void` | `execute()` Runs the various sub-builds.
    `protected java.lang.String` | `getDefaultBuildFile()` Get the default build file name to use when launching the task.
    `void` | `handleErrorFlush(java.lang.String output)` Pass output sent to System.err to the new project.
    `void` | `handleErrorOutput(java.lang.String output)` Pass output sent to System.err to the new project.
    `void` | `handleFlush(java.lang.String output)` Pass output sent to System.out to the new project.
    `int` | `handleInput(byte[] buffer, int offset, int length)` Process input into the ant task
    `void` | `handleOutput(java.lang.String output)` Pass output sent to System.out to the new project.
    `void` | `setAntfile(java.lang.String antfile)` This method builds the file name to use in conjunction with directories.
    `void` | `setBuildpath(Path s)` Set the buildpath to be used to find sub-projects.
    `void` | `setBuildpathRef(Reference r)` Buildpath to use, by reference.
    `void` | `setFailonerror(boolean failOnError)` Sets whether to fail with a build exception on error, or go on.
    `void` | `setGenericAntfile(java.io.File afile)` This method builds a file path to use in conjunction with directories.
    `void` | `setInheritall(boolean b)` Corresponds to `<ant>`'s `inheritall` attribute.
    `void` | `setInheritrefs(boolean b)` Corresponds to `<ant>`'s `inheritrefs` attribute.
    `void` | `setOutput(java.lang.String s)` Corresponds to `<ant>`'s `output` attribute.
    `void` | `setTarget(java.lang.String target)` The target to call on the different sub-builds.
    `void` | `setVerbose(boolean on)` Enable/ disable verbose log messages showing when each sub-build path is entered/ exited.

    - ### Methods inherited from class org.apache.tools.ant.Task

      `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

    - ### Methods inherited from class org.apache.tools.ant.ProjectComponent

      `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SubAnt

          public SubAnt()

  - ### Method Detail

    - #### getDefaultBuildFile

          protected java.lang.String getDefaultBuildFile()

      Get the default build file name to use when launching the task.

      This function may be overrided by providers of custom ProjectHelper so they can implement easily their sub launcher.

      Returns:
        the name of the default file
      Since:
        Ant 1.8.0

    - #### handleOutput

          public void handleOutput(java.lang.String output)

      Pass output sent to System.out to the new project.
      Overrides:
        `handleOutput` in class `Task`
      Parameters:
        `output` - a line of output
      Since:
        Ant 1.6.2

    - #### handleInput

          public int handleInput(byte[] buffer,
                        int offset,
                        int length)
                          throws java.io.IOException

      Process input into the ant task
      Overrides:
        `handleInput` in class `Task`
      Parameters:
        `buffer` - the buffer into which data is to be read.
        `offset` - the offset into the buffer at which data is stored.
        `length` - the amount of data to read
      Returns:
        the number of bytes read
      Throws:
        `java.io.IOException` - if the data cannot be read
      Since:
        Ant 1.6.2
      See Also:
        `Task.handleInput(byte[], int, int)`

    - #### handleFlush

          public void handleFlush(java.lang.String output)

      Pass output sent to System.out to the new project.
      Overrides:
        `handleFlush` in class `Task`
      Parameters:
        `output` - The output to log. Should not be `null`.
      Since:
        Ant 1.6.2

    - #### handleErrorOutput

          public void handleErrorOutput(java.lang.String output)

      Pass output sent to System.err to the new project.
      Overrides:
        `handleErrorOutput` in class `Task`
      Parameters:
        `output` - The error output to log. Should not be `null`.
      Since:
        Ant 1.6.2

    - #### handleErrorFlush

          public void handleErrorFlush(java.lang.String output)

      Pass output sent to System.err to the new project.
      Overrides:
        `handleErrorFlush` in class `Task`
      Parameters:
        `output` - The error output to log. Should not be `null`.
      Since:
        Ant 1.6.2

    - #### execute

          public void execute()

      Runs the various sub-builds.
      Overrides:
        `execute` in class `Task`

    - #### setAntfile

          public void setAntfile(java.lang.String antfile)

      This method builds the file name to use in conjunction with directories.

      Defaults to "build.xml". If `genericantfile` is set, this attribute is ignored.

      Parameters:
        `antfile` - the short build file name. Defaults to "build.xml".

    - #### setGenericAntfile

          public void setGenericAntfile(java.io.File afile)

      This method builds a file path to use in conjunction with directories.

      Use `genericantfile`, in order to run the same build file with different basedirs.

      If this attribute is set, `antfile` is ignored.
      Parameters:
        `afile` - (path of the generic ant file, absolute or relative to project base directory)

    - #### setFailonerror

          public void setFailonerror(boolean failOnError)

      Sets whether to fail with a build exception on error, or go on.
      Parameters:
        `failOnError` - the new value for this boolean flag.

    - #### setTarget

          public void setTarget(java.lang.String target)

      The target to call on the different sub-builds. Set to "" to execute the default target.
      Parameters:
        `target` - the target

    - #### addConfiguredTarget

          public void addConfiguredTarget(Ant.TargetElement t)

      Add a target to this Ant invocation.
      Parameters:
        `t` - the `TargetElement` to add.
      Since:
        Ant 1.7

    - #### setVerbose

          public void setVerbose(boolean on)

      Enable/ disable verbose log messages showing when each sub-build path is entered/ exited. The default value is "false".
      Parameters:
        `on` - true to enable verbose mode, false otherwise (default).

    - #### setOutput

          public void setOutput(java.lang.String s)

      Corresponds to `<ant>`'s `output` attribute.
      Parameters:
        `s` - the filename to write the output to.

    - #### setInheritall

          public void setInheritall(boolean b)

      Corresponds to `<ant>`'s `inheritall` attribute.
      Parameters:
        `b` - the new value for this boolean flag.

    - #### setInheritrefs

          public void setInheritrefs(boolean b)

      Corresponds to `<ant>`'s `inheritrefs` attribute.
      Parameters:
        `b` - the new value for this boolean flag.

    - #### addProperty

          public void addProperty(Property p)

      Corresponds to `<ant>`'s nested `<property>` element.
      Parameters:
        `p` - the property to pass on explicitly to the sub-build.

    - #### addReference

          public void addReference(Ant.Reference r)

      Corresponds to `<ant>`'s nested `<reference>` element.
      Parameters:
        `r` - the reference to pass on explicitly to the sub-build.

    - #### addPropertyset

          public void addPropertyset(PropertySet ps)

      Corresponds to `<ant>`'s nested `<propertyset>` element.
      Parameters:
        `ps` - the propertyset

    - #### addDirset

          public void addDirset(DirSet set)

      Adds a directory set to the implicit build path.

      Note that the directories will be added to the build path in no particular order, so if order is significant, one should use a file list instead!

      Parameters:
        `set` - the directory set to add.

    - #### addFileset

          public void addFileset(FileSet set)

      Adds a file set to the implicit build path.

      Note that the directories will be added to the build path in no particular order, so if order is significant, one should use a file list instead!

      Parameters:
        `set` - the file set to add.

    - #### addFilelist

          public void addFilelist(FileList list)

      Adds an ordered file list to the implicit build path.

      Note that contrary to file and directory sets, file lists can reference non-existent files or directories!

      Parameters:
        `list` - the file list to add.

    - #### add

          public void add(ResourceCollection rc)

      Adds a resource collection to the implicit build path.
      Parameters:
        `rc` - the resource collection to add.
      Since:
        Ant 1.7

    - #### setBuildpath

          public void setBuildpath(Path s)

      Set the buildpath to be used to find sub-projects.
      Parameters:
        `s` - an Ant Path object containing the buildpath.

    - #### createBuildpath

          public Path createBuildpath()

      Creates a nested build path, and add it to the implicit build path.
      Returns:
        the newly created nested build path.

    - #### createBuildpathElement

          public Path.PathElement createBuildpathElement()

      Creates a nested `<buildpathelement>`, and add it to the implicit build path.
      Returns:
        the newly created nested build path element.

    - #### setBuildpathRef

          public void setBuildpathRef(Reference r)

      Buildpath to use, by reference.
      Parameters:
        `r` - a reference to an Ant Path object containing the buildpath.